feat(okf): read/write notes as an Open Knowledge Format bundle + omind convert#144
Merged
Conversation
…nd convert` omind now conforms to the Open Knowledge Format (OKF v0.1, Google Cloud, Apache-2.0): every note omind writes leads with a YAML frontmatter block carrying the one field OKF requires (`type`) plus the recommended title/description/tags/ timestamp, and the vault's index.md is the OKF directory listing. Non-breaking by construction: - parse_note is dual-format — metadata is read from the legacy `## Metadata` section (which still wins for shared fields, so un-upgraded mesh peers keep working) OR the OKF frontmatter; the sole new source is the `type`. - render_fields regenerates the OKF frontmatter from the structured fields (deriving `type` from the note's kind — #feedback -> Feedback — when absent) and KEEPS the `## Metadata` block, so old omind reads created/tags/rev unchanged. Producer-defined frontmatter keys are round-tripped (OKF requires preserving unknown keys). Because omind already preserved a leading frontmatter block verbatim, an un-upgraded peer keeps OKF notes intact. - update_note now inherits tags/okf_type on a partial edit (like created/ frontmatter/lead), so an edit never silently drops frontmatter-authored tags. - the mesh merge driver carries `type` through three-way merges. New `omind convert` migrates a pre-OKF vault in place (idempotent — an already-OKF note renders byte-identical and is skipped, no revision bump; `--check` validates the three conformance rules, `--dry-run` previews). Also `omind.okf.convert_vault` / `check_conformance`. README leads with OKF (+ badge, spec links); CHANGELOG under [Unreleased]. ruff + mypy clean; full suite 739 passed (+14 OKF tests). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JFuGddPx3UhUkcC74KBXZB
CryptoJones
added a commit
that referenced
this pull request
Jul 2, 2026
Open Knowledge Format (OKF v0.1) support (#144): omind reads and writes notes as a conformant OKF bundle — YAML frontmatter with a required `type` on every note, dual -format backward-compatible parsing, and a new `omind convert` to migrate pre-OKF vaults in place. Non-breaking; existing vaults keep working with no migration. Version 3.7.8 -> 3.8.0 (pyproject + __init__ + uv.lock); CHANGELOG. Minor bump: new backward-compatible feature. ruff + mypy clean; full suite 739 passed. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JFuGddPx3UhUkcC74KBXZB
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
omind now reads and writes notes as a conformant Open Knowledge Format (OKF v0.1) bundle — Google Cloud's vendor-neutral, Apache-2.0 spec for representing knowledge as a directory of Markdown files with YAML frontmatter. It is non-breaking: existing vaults keep working with zero migration.
What changed
render_fieldsemits a YAML frontmatter block with the one field OKF requires (type, derived from the note's kind —#feedback->Feedback— when not declared) plus recommendedtitle/description/tags/timestamp.index.mdis the OKF directory listing.parse_notereads metadata from either the legacy## Metadatasection (which still wins for shared fields, so un-upgraded mesh peers keep working) or the frontmatter. The## Metadatablock is retained in every rendered note. Producer-defined frontmatter keys are round-tripped. Because omind already preserved a leading frontmatter block verbatim, an un-upgraded peer keeps OKF notes intact — safe to roll across the mesh incrementally.omind convert— migrate a pre-OKF vault in place. Idempotent (already-OKF note renders byte-identical -> skipped, no revision bump);--checkvalidates the three OKF conformance rules;--dry-runpreviews. Alsoomind.okf.convert_vault/check_conformance.update_noteinheritstags/okf_typeon a partial edit (likecreated/frontmatter/lead), so editing a note's summary never silently clears frontmatter-authored tags.typethrough three-way merges.[Unreleased].Verification
ruffclean,mypyclean (40 files)pytest: 739 passed, 1 skipped (+14 new OKF tests: conformance, conversion idempotency, dual-read, unknown-key preservation, CLI)convert --check(non-conformant) ->convert(1/1 conformant) -> re-run (0 converted, idempotent)Staged under
[Unreleased]; new backward-compatible feature -> 3.8.0.🤖 Generated with Claude Code
Proudly Made in Nebraska. Go Big Red! 🌽 https://xkcd.com/2347/